Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/sdk-ci.yml:
- Around line 32-35: Replace the non-deterministic version pin in the GitHub
Actions step that installs uv (the step named "Install uv" which uses
astral-sh/setup-uv@v4) so it no longer uses version: "latest"; update the
with.version value to a specific release (e.g., "0.11.6") or a stable semver
range (e.g., "0.11.x") to ensure reproducible CI runs.

In `@sdk/mkdocs.yml`:
- Around line 30-56: The mkdocs navigation references many missing documentation
pages so the site build will fail; create the docs directory and add the exact
markdown files referenced by the nav entries (e.g., index.md;
getting-started/install.md, getting-started/quickstart.md,
getting-started/concepts.md; cloud/overview.md, cloud/quickstart.md,
cloud/api.md, cloud/marketplace.md; guides/training.md,
guides/custom-domains.md, guides/mcp.md, guides/agent-graduation.md;
api/brain.md, api/cli.md, api/patterns.md; architecture/overview.md,
architecture/patterns.md, architecture/enhancements.md, architecture/brain.md,
architecture/agent-graduation.md) with at least a frontmatter/title and
placeholder content so mkdocs can build, ensuring file names and directory
structure match the nav keys (e.g., "Getting Started" => getting-started/*,
"Gradata Cloud" => cloud/*, etc.).
- Around line 58-67: The mkdocstrings handler in mkdocs config currently points
to the wrong source (paths: [src]) causing docs/CI to look for sdk/src; update
the mkdocstrings paths setting (under the mkdocstrings -> handlers -> python ->
paths key) to paths: [../src] so it correctly references the repository Python
package (or alternatively adjust SDK layout), and ensure this matches how the
SDK CI references src/gradata so both docs rendering and CI use the same ../src
location.

In `@src/gradata/brain.py`:
- Around line 346-356: The patch routine currently uses _find_lessons_path()
which may return external fallback files; change patch_rule to only allow edits
to the brain-local lessons file by resolving the canonical local path (e.g.
local = self.path.joinpath("lessons.md") or its resolved equivalent) and
verifying lessons_path is the same file or is_relative_to(self.path) before
proceeding; if the located lessons_path is external, return {"patched": False,
"error": "read_only: external lessons file"} and avoid calling
write_lessons_safe/format_lessons/apply_patch on external files (symbols:
_find_lessons_path, patch_rule, write_lessons_safe, format_lessons,
apply_patch).

In `@src/gradata/enhancements/meta_rules_storage.py`:
- Around line 447-450: The code opens sqlite3 connection (conn) and immediately
queries the correction_patterns table which can raise sqlite3.OperationalError
on a fresh DB; before running the SELECT, either (a) check for table existence
with a quick query like "SELECT name FROM sqlite_master WHERE type='table' AND
name='correction_patterns'" and skip/return empty if missing, or (b) wrap the
execute/select of correction_patterns in a try/except catching
sqlite3.OperationalError and returning an empty result; apply the same change to
the other block that queries correction_patterns (the block around lines
487-490) so read-only callers don't fail on an unbootstrapped db_path with no
tables.

In `@src/gradata/enhancements/rule_canary.py`:
- Around line 251-258: The emit call inside the promote-to-active block (the
emit("CANARY_PROMOTED", "rule_canary:promote_to_active", ... ) call in
rule_canary.py) is missing the BrainContext parameter; update this emit
invocation to pass the current BrainContext (as done in rollback_rule) so path
resolution is consistent—i.e., supply ctx (or the appropriate BrainContext
variable available in this scope) as the ctx argument and keep the existing
event name, action, payload, and tags.
- Around line 80-87: The brittle five-level parent traversal using
Path(__file__).resolve().parent.parent.parent.parent.parent to set scripts_dir
should be replaced with a robust resolution: either locate the installed "brain"
package via importlib (e.g., importlib.util.find_spec or
importlib.resources.files) and derive scripts_dir from that package location, or
iterate up the Path(__file__).resolve().parents in a small loop (check each
parent up to a sensible maximum) and test for "brain/system.db" rather than
hardcoding five parents; update the code that sets scripts_dir and p (the Path
for "brain/system.db") accordingly so existence checks remain the same but
resolution is resilient to package layout changes.
- Around line 148-158: The current SELECT uses a fragile LIKE on data_json;
change the query in the try block that builds corr_row to use JSON extraction
for the rule_category field instead (use json_extract(data_json,
'$.<fieldName>') = ? with the rule_category param and the same CAST(session AS
INTEGER) >= ? bound value) so you match the JSON key exactly; keep using
corr_row["cnt"] to set correction_count and preserve the existing except
fallback, but replace the LIKE pattern and parameter with an exact json_extract
comparison referencing the same rule_category variable and start_session.
- Around line 214-227: The emit call in rule_canary.py is missing the ctx
parameter required for proper path resolution and multi-brain support; update
the emit invocation in rollback_rule (the call that currently emits
"RULE_ROLLBACK", "rule_canary:rollback_rule", {...}) to pass the current
BrainContext (ctx) as the ctx argument (i.e., emit(..., ctx=ctx)) so it uses the
proper context rather than global state; ensure you import or reference the
existing BrainContext/ctx variable used elsewhere in the surrounding function if
necessary.

In `@src/gradata/enhancements/rule_integrity.py`:
- Around line 209-222: The _ensure_table function should use a context manager
for the SQLite connection: replace the explicit conn = sqlite3.connect(...) /
try / finally / conn.close() pattern with using "with
sqlite3.connect(str(db_path)) as conn:" so the connection is closed
automatically and commit is performed on successful exit; keep the CREATE TABLE
IF NOT EXISTS SQL and you can omit an explicit conn.close() (explicit
conn.commit() is optional inside the with-block but not required).
- Around line 159-169: The loop in extract_rule_signatures currently overwrites
signatures[category] with the last matched rule per category (using sign_rule
and _LESSON_PATTERN), which silently drops earlier rules; either change
signatures from dict[str, str] to dict[str, list[str]] (append each sig to
signatures[category]) and update the function return type/docstring to reflect
multiple signatures per category, or retain the single-signature design but add
a clear warning log whenever an existing signatures[category] would be
overwritten (include category and both old/new sigs) so overwrites are explicit;
locate this logic in extract_rule_signatures, where signatures is assigned and
where sign_rule(...) is called.

In `@src/gradata/enhancements/self_healing.py`:
- Around line 79-96: The comparison in apply_patch currently uses an exact
string match on lesson.description against old_description, which can fail with
whitespace differences; normalize both strings before comparing (e.g., collapse
consecutive whitespace and trim using a function like normalize = lambda s: "
".join(s.split())) and use normalize(lesson.description) ==
normalize(old_description) to find the lesson, then assign lesson.description =
new_description (leave new_description unchanged) and return the lesson as
before.

In `@src/gradata/hooks/_base.py`:
- Around line 84-97: Extract the hardcoded event tuple ("SessionStart", "Stop",
"PreCompact") into a descriptive module-level constant (e.g., EVENT_WHITELIST or
EVENTS_ALLOW_EMPTY_DATA) and update run_hook to reference that constant instead
of the inline list; ensure the constant is defined at top-level near other
module constants and include a short comment explaining its purpose so future
event additions only need to update the single constant used in the
meta.get("event") membership check inside run_hook.

In `@src/gradata/hooks/_installer.py`:
- Around line 14-16: The import order is inconsistent: _log is initialized
before other module imports; move the import of Profile (from
gradata.hooks._profiles) up into the top import block so all imports appear
before logger setup (ensure _log = logging.getLogger(__name__) remains after
imports), updating the symbols _log and Profile in
src/gradata/hooks/_installer.py accordingly.

In `@src/gradata/hooks/agent_graduation.py`:
- Around line 49-50: Replace the silent except block that currently reads
"except Exception: pass" with a debug log that captures the exception; e.g.,
change to "except Exception as e:" and call the module's logger (or
logging.getLogger(__name__)) at debug level including the exception information
(use logger.debug('agent_graduation hook failed', exc_info=e) or
logger.debug('agent_graduation hook failed: %s', e, exc_info=e)) so the hook
still swallows errors but records them for debugging in
src/gradata/hooks/agent_graduation.py (where the except block lives).

In `@src/gradata/hooks/agent_precontext.py`:
- Around line 47-58: The _relevance_score function currently gives a +0.2 bonus
only when lesson.state.name == "RULE"; modify _relevance_score to also award a
smaller bonus (e.g., +0.1) when lesson.state.name == "PATTERN" so PATTERN
lessons rank above lower tiers but below RULE; implement this by adding a
conditional branch checking lesson.state.name == "PATTERN" (or converting to
.lower() for case-insensitivity) and adding 0.1 to score where appropriate,
keeping the existing RULE branch unchanged.

In `@src/gradata/hooks/brain_maintain.py`:
- Around line 16-39: The _rebuild_fts function currently swallows all exceptions
silently; update its exception handlers to log suppressed exceptions at debug
level (including exception details/traceback) instead of using bare pass so
debugging is possible (mirror the pattern used in implicit_feedback.py).
Specifically, in _rebuild_fts wrap the outer try/except and the inner per-file
except Exception blocks to call the module or ctx logger (or a logger obtained
via logging.getLogger) and emit a debug-level message with the exception info
when fts_index or file reads fail, while preserving the silent/fail-safe
behavior for callers.

In `@src/gradata/hooks/config_protection.py`:
- Around line 15-25: PROTECTED_FILES currently includes "pyproject.toml", which
blocks all edits; remove "pyproject.toml" from the PROTECTED_FILES set (in
src/gradata/hooks/config_protection.py) so general project metadata and
dependency changes are allowed, or alternatively keep it but change the
protection logic that checks PROTECTED_FILES to parse the modified
pyproject.toml and deny only edits to tool-specific sections (e.g., [tool.ruff],
[tool.black], [tool.isort], etc.) by inspecting the diffed TOML keys before
rejecting the write.

In `@src/gradata/hooks/config_validate.py`:
- Around line 59-71: The repeated import of gradata.hooks and lookup of
hooks_pkg.__file__ inside the nested loops is inefficient; move the import and
resolution of hooks_dir outside the loops (once) — attempt a single import of
gradata.hooks into hooks_pkg, compute hooks_dir =
Path(hooks_pkg.__file__).parent (handle the import exception once and set a flag
to skip file checks if it fails), then inside the loop keep computing
module_name and module_path = hooks_dir / f"{module_name}.py" and append the
same warnings referencing event_name, i, j only if hooks_dir is available.

In `@src/gradata/hooks/duplicate_guard.py`:
- Around line 75-78: The _in_watched_dir function uses a substring check against
WATCHED_DIRS which can yield false positives (e.g. "/.../gradata_backup"
matching "src/gradata/"); change the logic to perform path-component-aware
matching: normalize file_path to a pathlib.Path (e.g.,
Path(file_path).as_posix() or Path(file_path).parts) and for each watched entry
(also normalized) check for exact path component boundaries (for example compare
Path(file_path).parts to the sequence of parts from Path(watched).parts or use
Path(file_path).resolve().match or startswith on the resolved path with a
normalized watched path + os.sep) so only true directory matches are accepted;
update _in_watched_dir to use pathlib and WATCHED_DIRS normalized parts to avoid
substring matches.

In `@src/gradata/hooks/implicit_feedback.py`:
- Around line 113-118: The imports currently inside the for cat in
categories_seen loop (from datetime import date as _date; from gradata._types
import Lesson, LessonState; from gradata.enhancements.self_improvement import
format_lessons, parse_lessons, INITIAL_CONFIDENCE; from gradata._db import
write_lessons_safe) should be moved to the top of the function (or module) that
contains the loop to avoid repeated import overhead; locate the loop named "for
cat in categories_seen" and remove those in-loop import statements, adding them
once at the start of the surrounding function or module so the code references
the same symbols ( _date, Lesson, LessonState, format_lessons, parse_lessons,
INITIAL_CONFIDENCE, write_lessons_safe) without re-importing each iteration.

In `@src/gradata/hooks/session_close.py`:
- Around line 23-35: In _run_graduation replace the direct
lessons_path.write_text(...) call with the existing locked writer
write_lessons_safe() to avoid unlocking races: after computing formatted =
format_lessons(active) call write_lessons_safe(brain_dir, formatted) (or the
module’s write_lessons_safe API) instead of Path.write_text; ensure you import
write_lessons_safe from gradata.enhancements.self_improvement alongside
parse_lessons/graduate/format_lessons and preserve UTF‑8 semantics and existing
exception handling.

In `@src/gradata/hooks/tool_failure_emit.py`:
- Around line 17-26: The ERROR_PATTERNS list contains a case-sensitive pattern
re.compile(r"\bException\b") which misses lowercase "exception" entries; modify
that element in ERROR_PATTERNS to use the re.I flag (i.e., compile
r"\bException\b" with re.I) so it matches case-insensitively, keeping the rest
of the list unchanged.

In `@src/gradata/hooks/tool_finding_capture.py`:
- Around line 116-121: The current loop in tool_finding_capture.py clears all
findings by calling _save_findings([]) as soon as any file basename matches;
change this to remove only the matched finding(s) from the findings list and
persist the reduced list via _save_findings(updated_findings). Specifically,
inside the nested loops where you iterate over findings and each
finding.get("files", []), detect matches using Path(f).name == file_basename,
collect the matching finding ids or indices (or filter by identity), build a new
list excluding those matched entries, then call _save_findings(new_findings) and
return the same result string; keep the existing variables (findings,
file_basename, Path, _save_findings) to locate and implement the change.

In `@tests/test_hooks_base.py`:
- Around line 24-27: The test test_get_profile_default contains a redundant
os.environ.pop("GRADATA_HOOK_PROFILE", None) after using patch.dict(os.environ,
{}, clear=True); remove the pop call so the test simply clears the environment
with patch.dict and asserts get_profile() == Profile.STANDARD, keeping
references to test_get_profile_default, patch.dict, get_profile, and
Profile.STANDARD to locate the change.

In `@tests/test_hooks_intelligence.py`:
- Around line 31-37: The test uses a hardcoded POSIX nonexistent path when
calling precontext_main in test_agent_precontext_no_brain; change it to use the
pytest tmp_path fixture (e.g., str(tmp_path / "missing")) and patch.dict with
that string so the path is platform-independent; apply the same replacement for
the other tests referenced (lines around 76-83, 262-265, 346-349, 377-380) that
currently hardcode "/nonexistent/..." paths and ensure test functions accept the
tmp_path fixture where needed.

In `@tests/test_hooks_learning.py`:
- Around line 22-24: The test does a direct float equality check on
rules_and_patterns[0].confidence which is fragile; change the assertion to use
pytest.approx for robust comparison (e.g., assert
rules_and_patterns[0].confidence == pytest.approx(0.92)) and ensure pytest is
available in the test namespace (import pytest if not already present) so that
the confidence comparison in tests/test_hooks_learning.py uses pytest.approx
rather than ==.

In `@tests/test_hooks_safety.py`:
- Around line 13-67: The test contains an intentional dummy secret in
test_secret_scan_blocks_openai_key that triggers a static-analysis false
positive; to fix, mark that test value as test-only so the scanner ignores it by
adding an inline suppression/comment on the content string (e.g., append a
recognized ignore token like "# nosec" or a project-specific Betterleaks
suppression comment and a short note "dummy test key"), or alternatively
consolidate cases by parametrizing the tests into a single
test_secret_scan_detection that iterates (content, should_block) and calls
scan_main, as shown in the reviewer example; update the test names
(test_secret_scan_blocks_openai_key or test_secret_scan_detection) and the
scan_main usage accordingly so the intent and suppression are clear.

---

Outside diff comments:
In `@src/gradata/hooks/claude_code.py`:
- Line 55: The expression payload.get("tool_output", "") is a dead/unassigned
expression; either remove this line or assign its result to a variable for later
use (e.g., tool_output = payload.get("tool_output", "")) wherever payload is
being processed in this module (referencing the payload variable in
src/gradata/hooks/claude_code.py) so the value is not discarded.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/gradata/enhancements/behavioral_extractor.py`:
- Around line 34-39: The current try/except around "from
gradata.enhancements.edit_classifier import _FACTUAL_RE" swallows ImportError
even when the module fails to import for other reasons; change the import
handling so that you only fall back to the regex when the module truly does not
exist. Use importlib.util.find_spec("gradata.enhancements.edit_classifier") (or
similar) to detect absence: if the spec is None, set the fallback _FACTUAL_RE;
otherwise re-raise the original import exception so real import errors in
gradata.enhancements.edit_classifier are not masked. Ensure the code still
defines _FACTUAL_RE when the module is missing but does not hide other failures.
- Around line 427-433: The _is_actionable check is too permissive: replace the
broad "capitalized and 3+ words" rule in _is_actionable with a stricter
first-word verb check — e.g., create a small whitelist like _IMPERATIVE_VERBS
(or use the project POS-tagger if available) and change the second branch to
return True only when first_word.lower() is in _IMPERATIVE_VERBS (or when POS
tagger marks the first token as a verb), while keeping the existing
_IMPERATIVE_STARTERS/PREFIX_INSTRUCTION acceptance; update the logic in
_is_actionable accordingly to avoid accepting generic capitalized declaratives.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/gradata/_context_compile.py`:
- Around line 100-101: The except block in src/gradata/_context_compile.py
currently returns the raw exception string (return f"[context compile error:
{e}]") which can leak internals; instead catch the exception, log the full
exception details internally (e.g., logger.exception or logging.exception) for
diagnostics, and return a generic non-sensitive message such as "[context
compile error]" (or an empty/neutral string) to the caller; add or reuse a
module logger via logging.getLogger(__name__) if needed and remove any exposure
of the exception object from the returned value.

In `@src/gradata/contrib/patterns/tree_of_thoughts.py`:
- Around line 139-143: The "Never ..." candidate is being created with a global
replace that can remove internal "always " tokens; instead compute a single
normalized base string from lesson_description (e.g., base =
lesson_description.lower().removeprefix('always ').strip()) and reuse that base
for both the "Always ..." and "Never ..." candidates so you build candidates as
lesson_description, f"Always {base}", and f"Never {base}" (use the same
normalization logic referenced in the existing second candidate).

In `@src/gradata/enhancements/behavioral_extractor.py`:
- Around line 204-205: The list comprehension using zip(final_sents,
final_sent_sets, strict=True) can raise ValueError on a length mismatch; replace
the use of zip(..., strict=True) with a normal zip and add an explicit length
check (e.g., if len(final_sents) != len(final_sent_sets): raise
ValueError("final_sents and final_sent_sets length mismatch") ) before the
comprehension to produce a clearer, controlled error message; make the same
change for the other occurrences of zip(..., strict=True) that pair draft/final
sentence lists (referencing the variables final_sents, final_sent_sets,
draft_sent_sets and the _sentence_overlap usage) so all mismatches are detected
with a clear assertion instead of the zip strict ValueError.

In `@src/gradata/enhancements/meta_rules_storage.py`:
- Around line 70-72: Replace the broad
contextlib.suppress(sqlite3.OperationalError) used when executing
schema-altering statements (the loop that runs _ADD_CONTEXT_WEIGHTS_SQL,
_ADD_APPLIES_WHEN_SQL, _ADD_NEVER_WHEN_SQL, _ADD_TRANSFER_SCOPE_SQL) with a
try/except that catches sqlite3.OperationalError as e and re-raises unless the
error message indicates a duplicate column (e.g., contains "duplicate column" or
"duplicate column name", case-insensitive); do the same replacement for the
analogous super_meta_rules migration loop (the statements executed around the
second suppression block) so only duplicate-column errors are ignored and all
other OperationalError cases propagate.

In `@src/gradata/enhancements/rule_evolution.py`:
- Around line 281-284: Compute _detect_opposite_direction(new_desc,
best_rule.description) once into a local variable (e.g., opposite) before the
two if checks and then use that variable in the conditions instead of calling
_detect_opposite_direction twice; update the branching that returns
(RuleRelation.UPDATES, best_rule) and (RuleRelation.EXTENDS, best_rule) to
reference the new variable while retaining the same comparisons against
best_similarity, update_threshold, and extend_threshold (ensure you only
evaluate opposite when best_rule is not None).

In `@src/gradata/hooks/brain_maintain.py`:
- Around line 51-64: The main function currently returns None unconditionally;
update main (and its exit paths) to return a meaningful status dict on success
(e.g., {"result":"maintenance complete"}) while preserving the existing
early-return when resolve_brain_dir() yields falsy; keep exception handling but
return an error status on failure or rethrow if preferred. Specifically, in
function main (uses resolve_brain_dir(), BrainContext.from_brain_dir,
_rebuild_fts, _generate_manifest) change the final return to a success dict
after _generate_manifest completes, and ensure the early branch that returns
when not brain_dir still returns an explicit status (e.g., {"result":"no brain
dir"}) and the except block returns or logs an error status (e.g.,
{"error":"..."}).

In `@src/gradata/hooks/context_inject.py`:
- Around line 44-46: The loop handling search results assumes each result r is a
dict and uses r.get(), which fails for object results; update the extraction to
try object attributes first (getattr(r, "text", None) or getattr(r, "content",
None)), then fall back to dict access (r.get("text") or r.get("content")) and
finally str(r) so both dicts and objects from brain.search() are handled; modify
the snippet around the for r in results loop in context_inject.py to use this
attribute-or-key fallback for text/snippet extraction.

In `@src/gradata/hooks/inject_brain_rules.py`:
- Around line 33-58: Wrap the file I/O and parsing steps in a broad try/except
inside main so any exceptions from lessons_path.read_text, parse_lessons, or
related operations are caught and the hook returns None (silent failure) instead
of raising; specifically, around the block that calls resolve_brain_dir(), reads
lessons.md via lessons_path.read_text(), calls parse_lessons(text), and
processes results (including filtered/scored/lines/block), catch Exception and
return None. Keep existing early-return checks (resolve_brain_dir and is_file)
but ensure unexpected errors during I/O or parsing do not propagate.

In `@src/gradata/hooks/pre_compact.py`:
- Line 68: The MD5 call used to generate dir_hash is incompatible with
FIPS-enabled Python because it omits the usedforsecurity flag; update the call
that constructs dir_hash in pre_compact.py (the hashlib.md5(...) that encodes
str(brain_dir)) to pass usedforsecurity=False so the non-cryptographic
filename-uniqueness hash works on FIPS systems, keeping the rest of the logic
(encoding and hexdigest slicing) unchanged.

In `@src/gradata/hooks/rule_enforcement.py`:
- Around line 24-50: Wrap the file I/O and parsing steps in main with exception
handling so no exceptions escape the hook: around resolve_brain_dir(),
lessons_path.read_text(...), and the parse_lessons(text) call (and the loop that
builds rules using MAX_REMINDERS), catch broad exceptions, optionally log at
debug if a logger exists, and return None on error; ensure parse_lessons being
None is still handled as before and that the function never lets file or parsing
errors propagate.

In `@src/gradata/hooks/secret_scan.py`:
- Around line 44-73: The main function lacks defensive error handling; wrap the
body of main (which builds contents_to_scan, iterates edits, calls
_scan_content, and assembles the findings/return value) in a try/except that
catches Exception and returns None on error to match other hooks (e.g.,
implicit_feedback.py, context_inject.py). Ensure the try block includes all
logic that reads tool_input, constructs contents_to_scan, calls _scan_content,
and builds the final decision payload, and that the except logs or swallows the
exception and returns None so failures in _scan_content or unexpected input
don't crash the hook.

In `@src/gradata/hooks/session_persist.py`:
- Around line 68-93: Remove the redundant try/except in the main function of
session_persist.py: delete the surrounding try/except block so main(data: dict)
executes its logic directly and lets run_hook's wrapper (run_hook in _base.py)
handle exceptions; ensure the function still returns None at the end and keeps
all existing behavior (resolve_brain_dir(), _get_session_number(),
_get_modified_files(), file write to persist_dir) unchanged.

In `@src/gradata/integrations/openai_adapter.py`:
- Around line 98-99: The patched client currently stores Brain on client._brain
and calls brain.log_output() and brain.observe() inside patched_create, which is
unsafe for multi-threaded use; fix by adding a threading.RLock (e.g.,
client._brain_lock = threading.RLock()) when you attach the brain and wrap all
Brain accesses in patched_create (acquire the lock around calls to
brain.log_output() and brain.observe()) to serialize SQLite writes;
alternatively, if you prefer not to add locking, update the module/class
docstring and add a clear comment where client._brain is set stating the patched
client MUST NOT be shared across threads and recommend one Brain per process or
using process-level locks (reference symbols: Brain, patched_create,
client._brain, client.chat.completions.create, brain.log_output(),
brain.observe()).

---

Outside diff comments:
In `@src/gradata/__init__.py`:
- Around line 1-26: Add the postponed-annotations future import at the very top
of the module: insert from __future__ import annotations as the first statement
in this file (before the module docstring and any other imports) so the typing
rule is satisfied for the core SDK; keep the rest of the file (the module
docstring, __version__, and the logging/os imports) unchanged.

In `@src/gradata/_context_compile.py`:
- Around line 8-15: Add the postponed annotations import at the top of the
module: insert "from __future__ import annotations" as the first statement (or
immediately after any module docstring) in src/gradata/_context_compile.py so
the file complies with the core SDK typing standard; this will ensure forward
references work for the existing TYPE_CHECKING import and the referenced
BrainContext type usage.

In `@src/gradata/_doctor.py`:
- Around line 246-264: The print_diagnosis function in src/gradata/_doctor.py
currently calls print() for all output; replace these prints with structured
logging (e.g., get a module logger via logging.getLogger(__name__) and emit
logger.info for normal lines, logger.warning for "degraded" messages and
logger.error for the failing status) or alternatively return the formatted
multi-line string from print_diagnosis and let the CLI layer print it; update
the loop over report["checks"] to log each check with
icons.get(check["status"]), the humanized name and detail instead of printing,
and ensure the final status block uses the appropriate logger level (healthy →
info, degraded → warning, else → error) so no print() calls remain in the
module.

In `@src/gradata/_manifest_helpers.py`:
- Around line 8-15: Add the required postponed-annotations import at the top of
the gradata._manifest_helpers module by inserting "from __future__ import
annotations" as the very first import statement so the file (module
gradata._manifest_helpers) uses postponed evaluation of type annotations and
conforms to the core SDK typing standard; ensure it appears before any other
imports such as re, typing.TYPE_CHECKING, gradata._paths, and
gradata._db.get_connection.

In `@src/gradata/_migrations.py`:
- Around line 80-92: The migration code opens a SQLite connection with
get_connection(db_path) and manually calls conn.commit() and conn.close(), which
can leak the connection if an exception occurs; change the block that iterates
over _BASE_TABLES and _MIGRATIONS to use a context manager (e.g., "with
get_connection(db_path) as conn:" or wrap in try/finally) so the connection is
always closed and commit is done inside the managed scope; ensure the loops over
_BASE_TABLES and _MIGRATIONS still execute the same operations (suppressing
sqlite3.OperationalError for base tables and counting applied migrations) and
that applied counting and conn.commit() occur within the context so cleanup is
guaranteed even on errors.
- Around line 76-93: Change run_migrations to accept a BrainContext parameter
(e.g. def run_migrations(ctx: BrainContext) -> int) and use the context's DB
path when opening the connection (call get_connection(ctx.db_path) instead of
get_connection(db_path)); open the connection with a context manager (with
get_connection(ctx.db_path) as conn:) so executes/commit are cleaned up
automatically, remove the explicit conn.close(), and update the caller to pass
the BrainContext from where run_migrations is invoked.

In `@src/gradata/_tag_taxonomy.py`:
- Around line 12-16: The module gradata._tag_taxonomy is missing the required
typing future import; add the line "from __future__ import annotations" at the
top of the file before any other imports so the module meets the SDK typing
baseline and enables postponed evaluation of annotations used by
functions/classes in this module.

In `@src/gradata/contrib/enhancements/install_manifest.py`:
- Line 499: Move the function-local "import time" into the module-level imports
in install_manifest.py: add time to the existing top-of-file imports alongside
the other standard-library imports and remove the in-function "import time"
statement so the module uses the top-level time import throughout (locate the
in-function import in the function where "import time" currently appears and
delete it after adding the module-level import).

In `@src/gradata/contrib/patterns/guardrails.py`:
- Around line 637-648: In check_fn (the closure returned in this block), remove
the dead expression `str(data).lower() if data else ""` and instead compute and
reuse a normalized output string (e.g., text = str(data).lower() or "") to
perform a real heuristic check: parse the rule_text phrase for simple patterns
like "never <term>" or "always <term>" and set GuardCheck.result to "fail" when
the heuristic finds a violation (and "pass" otherwise); populate
GuardCheck.details with the matched term and a short reason, include rule name
using rule_cat (as now), and set action_taken to the concrete action you want
for fail vs pass so the guard is not always a no-op. Ensure you reference the
existing symbols check_fn, rule_text, rule_cat, and GuardCheck when making
changes.
- Line 633: Remove the dead expression `rule.principle.lower()` that computes a
value and discards it; either delete that statement entirely or, if the intent
was to normalize the principle, assign the lowercased value back (e.g., set
`rule.principle = rule.principle.lower()` or call the appropriate normalization
method). Update the code in the same scope where `rule.principle.lower()`
appears so the normalized value is actually used or the no-op is eliminated.
- Around line 614-629: The function guards_from_graduated_rules currently
obtains DB access via get_rule_context() and ctx.for_guardrails(), but must
accept a BrainContext parameter instead; change the signature of
guards_from_graduated_rules to accept a BrainContext (e.g., def
guards_from_graduated_rules(brain_ctx: BrainContext) -> list[Guard]), remove the
internal import/usage of get_rule_context(), and use the provided brain_ctx to
call for_guardrails (or obtain ctx from brain_ctx if needed); update any call
sites to pass the BrainContext and adjust imports/types to include BrainContext
and maintain the same return behavior from ctx.for_guardrails().

In `@src/gradata/enhancements/git_backfill.py`:
- Line 190: The parameter brain currently typed as Any should use a stricter
type: define a Protocol (e.g., BrainLike) that declares the methods used (at
least correct(self, draft: str, final: str, session: int | None = None) ->
dict[str, Any]) or, if a concrete Brain class exists, use a forward reference to
that class; then update the function/method signature that contains "brain: Any"
in git_backfill.py to use BrainLike or "Brain" instead and import
typing.Protocol and typing.Any as needed so type checkers can validate usages of
brain.correct and related calls.

In `@src/gradata/enhancements/quality_monitoring.py`:
- Around line 177-178: The alert message in the being_ignored detector currently
prints correction densities in the wrong order; change the f-string in the Alert
returned in quality_monitoring.py so it shows previous.correction_density before
current.correction_density (i.e., f"Corrections dropped
{previous.correction_density:.2f} → {current.correction_density:.2f} ...") and
keep the rest of the message (including edit_distance_avg from current)
unchanged so the arrow correctly indicates the drop.

In `@src/gradata/enhancements/router_warmstart.py`:
- Around line 37-120: The warm_start_router function currently opens sqlite3
directly (sqlite3.connect) which bypasses BrainContext; change warm_start_router
to accept a BrainContext parameter (e.g., ctx: BrainContext) instead of db_path,
use ctx DB access methods (connection/execute/row fetching or a provided query
helper) to read CORRECTION events, remove direct sqlite3 usage, and preserve the
existing logic that constructs QLearningRouter (RouterConfig), calls
router.route/reward_from_severity/update_reward, and router.load/save; also
update any callers to pass a BrainContext and ensure the function uses ctx’s
transaction/cleanup semantics rather than manually opening/closing sqlite3
connections.

In `@src/gradata/integrations/openai_adapter.py`:
- Line 35: The patch_openai function currently uses a hardcoded default
brain_dir "./brain"; remove that hardcoded default by making brain_dir a
required parameter (change signature to patch_openai(client: Any, brain_dir: str
| Path)) or alternatively default it from an environment variable (e.g.,
os.environ.get("GRADATA_BRAIN_DIR")) and validate it is set; update callers to
pass brain_dir, add an import for os if using env var, and add a clear
error/exception in patch_openai if brain_dir is missing or invalid to prevent
silent failures.
- Around line 87-89: The code accesses response.choices[0] without checking that
response.choices is non-empty, which can raise IndexError; modify the block
handling the OpenAI response in openai_adapter.py to first verify that
response.choices exists and has at least one element (e.g., if response.choices
and len(response.choices) > 0) before reading
response.choices[0].message.content, only then assign ai_content and call
brain.log_output(ai_content, output_type="chat"); keep the surrounding
try/except but use this explicit bounds check to avoid the vague "Response
capture skipped" path and to short-circuit cleanly when no choices are present.

---

Duplicate comments:
In `@src/gradata/hooks/agent_graduation.py`:
- Around line 24-51: The hook currently swallows all exceptions in main (and
thus loses error context); add debug-level logging to capture exceptions: import
logging and create a module logger (e.g., logger = logging.getLogger(__name__)),
then inside the except block of main (and optionally where resolve_brain_dir()
returns falsy) call logger.debug with a clear message and exc_info=True so the
traceback and exception are recorded; reference the main function,
resolve_brain_dir(), _infer_agent_type(), BrainContext.from_brain_dir, and emit
to indicate where failures should be logged.

In `@src/gradata/hooks/session_close.py`:
- Around line 24-39: The current _run_graduation function writes lessons
atomically via lessons_path.write_text(), which can race with other writers;
replace that direct write with the project's locked writer utility
write_lessons_safe (import it from its module) and call it with the lessons
target and formatted content (use format_lessons(active)) so the lessons file is
updated under the safe/locked write path instead of lessons_path.write_text().

In `@src/gradata/hooks/tool_failure_emit.py`:
- Around line 17-26: The regex for matching "Exception" in the ERROR_PATTERNS
list is case-sensitive; update the re.compile(r"\bException\b") entry in
ERROR_PATTERNS to be case-insensitive (e.g., add the re.I flag or use a
case-insensitive inline modifier) so it matches "exception" as well; locate the
ERROR_PATTERNS constant and modify the specific re.compile call for
"\bException\b" accordingly.